Deploy the Stack

There are two ways in, and they're equivalent. We'd use the console the first time, because the template's interface metadata groups the parameters and labels the conditional ones, and switch to the CLI once the parameter set has stabilised and we're rebuilding environments repeatedly. Either route creates the stack from the single file yeedu-platform.yaml, and either route needs the CAPABILITY_NAMED_IAM acknowledgement before CloudFormation will proceed.

Pick whichever suits you.

Via the AWS console

1. Sign in to the AWS Management Console and switch to your target region.
2. Open CloudFormation and choose Create stack, then With new resources (standard).
3. Under Specify template, choose Upload a template file and select yeedu-platform.yaml.
4. Enter a stack name. It matters more than it looks, because the S3 bucket is named ${AWS::StackName}-data and the stack name is baked into the IAM user name and both Secrets Manager secret names.
5. Fill in the parameters. The form shows six sections, and the RDS and HTTPS fields carry labels reminding you when they become mandatory.
6. On Configure stack options, scroll to Capabilities and tick the acknowledgement that CloudFormation may create IAM resources with custom names.
7. Review the summary and create the stack.

Via the AWS CLI

Put the parameters in a file. Only keys that exist in the template are accepted, and anything else is rejected outright with a message naming the offending key. Here's the set we use for a full deployment with the database, the registries and the log groups all switched on.

[
  { "ParameterKey": "EnvironmentName",             "ParameterValue": "dev" },
  { "ParameterKey": "VpcId",                       "ParameterValue": "vpc-0ca4a329daff73bbb" },
  { "ParameterKey": "Ec2SubnetId",                 "ParameterValue": "subnet-0d12439a87299d35d" },
  { "ParameterKey": "Ec2ImageId",                  "ParameterValue": "ami-0e420a966bea7857b" },
  { "ParameterKey": "Ec2InstanceType",             "ParameterValue": "c6a.2xlarge" },
  { "ParameterKey": "Ec2KeyName",                  "ParameterValue": "your-key-name" },
  { "ParameterKey": "AssignPublicIp",              "ParameterValue": "true" },
  { "ParameterKey": "YeeduVersion",                "ParameterValue": "v2.9.1" },
  { "ParameterKey": "RdsCreate",                   "ParameterValue": "true" },
  { "ParameterKey": "RdsInstanceClass",            "ParameterValue": "db.m5.large" },
  { "ParameterKey": "RdsEngineVersion",            "ParameterValue": "15.12" },
  { "ParameterKey": "RdsSubnet1Id",                "ParameterValue": "subnet-0123456789abcdef1" },
  { "ParameterKey": "RdsSubnet2Id",                "ParameterValue": "subnet-0123456789abcdef2" },
  { "ParameterKey": "CreateLogGroups",             "ParameterValue": "true" },
  { "ParameterKey": "CreateContainerRepositories", "ParameterValue": "true" }
]

Then create the stack.

aws cloudformation create-stack \
  --stack-name yeedu-platform \
  --template-body file://yeedu-platform.yaml \
  --parameters file://parameters.json \
  --capabilities CAPABILITY_NAMED_IAM

caution

The parameters.json.example file shipped next to the template still lists AwsRegion, YeeduDockerUsername and YeeduDockerPassword. None of those three are template parameters any more. Passing them makes create-stack fail immediately with a message that they don't exist in the template, so we strip them out before using that file.

Without RDS, ECR or log groups

The smallest useful deployment leaves all four booleans at false and passes only the three required values, plus an environment name and a key pair. Everything runs on the single instance.

aws cloudformation create-stack \
  --stack-name yeedu-platform \
  --template-body file://yeedu-platform.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters \
    ParameterKey=EnvironmentName,ParameterValue="dev" \
    ParameterKey=VpcId,ParameterValue="vpc-0ca4a329daff73bbb" \
    ParameterKey=Ec2SubnetId,ParameterValue="subnet-0d12439a87299d35d" \
    ParameterKey=Ec2ImageId,ParameterValue="ami-0e420a966bea7857b" \
    ParameterKey=Ec2InstanceType,ParameterValue="c6a.2xlarge" \
    ParameterKey=Ec2KeyName,ParameterValue="your-key-name"

Watching it come up

Creation takes a while, and most of that is the RDS instance when you've asked for one. These are the three calls we keep reaching for.

aws cloudformation describe-stacks --stack-name yeedu-platform
aws cloudformation list-stack-resources --stack-name yeedu-platform
aws cloudformation describe-stack-events --stack-name yeedu-platform

For something closer to a live view, wrap the status query in watch.

watch -n 10 "aws cloudformation describe-stacks --stack-name yeedu-platform \
  --query 'Stacks[0].StackStatus' --output text"

warning

CREATE_COMPLETE means AWS finished creating resources. It does not mean Yeedu is running. The template declares no CreationPolicy and sends no cfn-signal, so CloudFormation stops paying attention the moment the instance launches, while the user data script is still installing Docker, syncing the release from s3://yeedu-softwares and starting containers. We confirm the platform separately, as described in Post-Deployment.

Deleting the stack

Deletion terminates the instance and removes the file system, the secrets and the database, so take a snapshot or a backup of anything you care about first.

aws cloudformation delete-stack --stack-name yeedu-platform

Two things survive deliberately, and one blocks the delete.

The 17 ECR repositories and the 10 CloudWatch log groups all carry DeletionPolicy: Retain, so they stay behind deliberately and your container images and logs outlive the stack that created them. That's convenient right up until you redeploy, at which point creating them a second time fails because the names are already taken. Set CreateContainerRepositories and CreateLogGroups to false on the second run.

The S3 bucket has to be empty before CloudFormation can remove it. If deletion fails on YeeduBucket, clear it and retry.

aws s3 rm s3://${STACK_NAME}-data --recursive